Workflow Builder

Workflow construction provides a structured way to define and compose BindAI execution processes. A workflow definition coordinates agents, tools, conditions, loops, parallel operations, human tasks, Memory, Knowledge, and configured Connections. BindAI documentation should distinguish between the workflow construction model and a specific builder API. A class or method should only be documented as public API when it exists in the current implementation.

Why Use Structured Workflow Construction?

Complex execution processes become difficult to maintain when orchestration logic is placed inside a single function or agent. A structured workflow separates:

Execution steps
Control flow
Workflow state
Agent execution
Tool execution
Human interaction
External operations

Conceptually:

Workflow Definition
        |
        v
Execution Structure
        |
        v
Workflow Run

This makes the application process easier to understand and test.

Workflow Construction Lifecycle

A workflow can generally be understood through four stages:

Define
  |
  v
Configure
  |
  v
Save
  |
  v
Execute

The exact construction mechanism depends on the workflow interface being used. BindAI Studio provides a visual workflow editor where users can construct and save workflow definitions. The runtime then loads those definitions and executes them.

Workflow Definition

A workflow definition describes the nodes in a process and the relationships between them. A simple workflow might be:

Start
  |
  v
Agent
  |
  v
Tool
  |
  v
End

A more complex workflow can contain branches:

                 +--> Agent A --+
                 |              |
Start --> Condition             +--> End
                 |              |
                 +--> Agent B --+

The workflow definition determines how execution moves between these operations.

Workflow Nodes

BindAI V1 supports the following workflow nodes:

Start
End
Agent
Tool
Condition
Loop
Parallel
Join
Human Task

Each node has a specific responsibility. For example:

Start
  |
  v
Agent
  |
  v
Condition
 /       \
true     false
 |         |
 v         v
Tool      End
 |
 v
End

Agents as Workflow Steps

An agent can perform reasoning within a workflow.

Workflow
   |
   v
Research Agent
   |
   v
Agent Result
   |
   v
Next Node

Different agents can specialize in different parts of a larger process. Agent nodes can receive workflow values as input and store their output in a workflow variable. For example:

input
  |
  v
Agent
  |
  v
agent_output

That output can then be consumed by another workflow node.

Tools as Workflow Steps

Tools perform executable operations.

Workflow
   |
   v
Tool
   |
   v
ToolResult
   |
   v
Next Node

BindAI tools use the Tool and ToolResult abstractions. A successful tool execution provides a value. A failed execution provides an error. Tools can also be backed by configured Connections. For example:

Workflow
   |
   v
Webhook Connection Tool
   |
   v
External Webhook

This provides a real execution path from the workflow to an external service.

Sequential Construction

The simplest workflow is sequential:

Start
  |
  v
Step A
  |
  v
Step B
  |
  v
Step C
  |
  v
End

Sequential execution is appropriate when each operation depends on the previous operation. Examples include:

Load Data
    |
    v
Transform
    |
    v
Validate
    |
    v
Complete

and:

Research
    |
    v
Write
    |
    v
Review

Conditional Construction

Conditions allow a workflow to select an execution path.

                 +--> Continue
                 |
Step --> Condition
                 |
                 +--> Stop

A condition evaluates an expression using workflow state. For example:

Agent
  |
  v
Condition
 /        \
true      false
 |          |
 v          v
Continue   End

Conditional execution is useful for:

Validation
Routing
Approval decisions
Result-based branching
Workflow control

Loop Construction

Loops allow a workflow to repeat operations.

Process
   |
   v
Condition
 /       \
more     done
 |         |
 v         v
Loop      End
 |
 +----> Process

Common uses include:

Processing collections
Repeated processing
Iterative operations
Processing items until a condition is satisfied

Loops should have explicit termination conditions.

Parallel Construction

Independent operations can be executed in parallel.

             +--> Agent A --+
             |              |
Start --> Parallel           +--> Join --> End
             |              |
             +--> Agent B --+

Parallel execution is useful when branches do not depend on each other’s intermediate results. Typical uses include:

Independent agent execution
Independent tool operations
Separate analysis tasks
Independent workflow branches

Join Construction

A Join node provides the synchronization point after parallel branches.

             +--> Branch A --+
             |               |
Start --> Parallel           +--> Join --> Next
             |               |
             +--> Branch B --+

The Join node allows the workflow to continue after the required parallel branches have completed.

Human Task Construction

A workflow can include human interaction when automated execution should pause for review.

Agent
  |
  v
Human Task
  |
  +--> approved --> Continue
  |
  +--> rejected --> Alternative Path

Human Tasks are useful for:

Approval workflows
Content review
Sensitive actions
Compliance processes
Human-in-the-loop decisions

A workflow waiting for a Human Task does not simply finish. The workflow instance remains in a waiting state and can later be resumed with the human action.

Workflow State

Multi-step workflows require information to move between operations. Conceptually:

Step A
  |
  v
State
  |
  v
Step B
  |
  v
Updated State
  |
  v
Step C

Workflow state can contain values produced by previous nodes. For example:

input
agent_output
tool_output

A later node can consume values produced by earlier nodes. Workflow state should be distinguished from persistent Memory:

Workflow state supports the current workflow execution.
Memory provides retained information for agent interactions.

Memory in Workflows

Memory can be used by agents executing inside workflows. For example:

Workflow
   |
   v
Agent
   |
   +--> Memory
   |
   v
Tool
   |
   v
End

Configured Memory can persist agent conversation context between executions. Memory and workflow state are separate concepts and serve different purposes.

Knowledge in Workflows

Knowledge can be used by agents executing inside workflows. For example:

Workflow
   |
   v
Agent
   |
   +--> Knowledge
   |
   v
Tool
   |
   v
End

Configured Knowledge provides searchable information that can be used during agent execution. A workflow can therefore coordinate agents that use both Memory and Knowledge.

Connections in Workflows

BindAI V1 supports Webhook connections as executable workflow integrations. The architecture is:

Connection
    |
    v
Connection-backed Tool
    |
    v
Workflow

For example:

Start
  |
  v
Agent
  |
  v
Webhook Tool
  |
  v
External Webhook
  |
  v
End

The connection stores the provider configuration while the connection-backed tool exposes the operation to the workflow. The Webhook connection sends a JSON payload through HTTP POST. Additional connection providers are planned for future versions.

Visual Workflow Construction

BindAI Studio provides a visual workflow editor for constructing workflow graphs. The editor supports:

Start and End nodes
Agent nodes
Tool nodes
Condition nodes
Loop nodes
Parallel and Join nodes
Human Task nodes

The visual editor represents the workflow definition that is later loaded by the runtime. The purpose of the editor is therefore not only to visualize a process. Saved workflow definitions can be executed by the runtime.

Workflow Construction and Execution

Construction and execution are separate concerns. Conceptually:

Construct
    |
    v
Save Workflow
    |
    v
Load Definition
    |
    v
Build Runtime Workflow
    |
    v
Execute

A workflow can be constructed through Studio and then executed through the Studio API. The runtime resolves the configured agents, tools, connections, and other workflow dependencies.

Workflow Execution Through the Studio API

Studio workflows can be executed through the BindAI API. An execution receives workflow variables as input. Conceptually:

API Request
    |
    v
Workflow
    |
    v
Execution
    |
    +--> Completed
    |
    +--> Waiting for Human Task

When a Human Task pauses execution, the workflow instance identifier can be used to resume the workflow after the human action is provided.

Workflow Persistence

BindAI V1 supports persistent workflow execution state in the Studio runtime. Persisted workflow instances can contain information such as:

Workflow identifier
Workflow version
Workflow variables
Execution state
Human-task state
Execution timestamps
Errors
Completion state

Persistence allows a workflow waiting for a Human Task to survive beyond the original execution request.

Builder APIs and Documentation Accuracy

The term Workflow Builder describes a construction concept. It does not necessarily mean that BindAI exposes a class named WorkflowBuilder. For example, a framework might use an API such as:

builder = WorkflowBuilder(...)

or:

workflow = WorkflowBuilder(...).step(...).build()

These examples should not be treated as BindAI API examples unless those exact classes and methods exist in the current implementation. Documentation should not invent methods such as:

.start_node()
.agent()
.tool()
.end_node()
.build()

unless they are verified against the installed BindAI version.

Builder vs Workflow Definition

The distinction is:

Concept	Purpose
Workflow definition	Describes the execution process
Builder	A possible mechanism for constructing the definition
Workflow runtime	Executes the resulting workflow

BindAI Studio currently provides the visual construction layer for workflow definitions. The runtime is responsible for executing those definitions.

Validation

Workflow definitions should be validated before relying on them in an application. BindAI provides CLI workflow validation:

bindai workflow validate ./workflows/research_workflow.py

For projects using the configured workflow entrypoint:

bindai workflow validate

Validation should be understood as a runtime/framework capability rather than a claim that every possible graph error is detected. Documentation should only describe specific validation rules when they are implemented and verified.

Workflow Execution Errors

Workflow execution can fail at different levels:

Workflow
   |
   +--> Agent Failure
   |
   +--> Tool Failure
   |
   +--> Connection Failure
   |
   +--> Validation Failure

Applications should consider how important failure paths should be handled. Depending on the operation, this may include:

Conditional branching
Human review
Stopping execution
Recording the failure
Handling the failure inside the tool or agent

Advanced retry and timeout policies are outside the current V1 workflow scope.

Building Large Workflows

Large workflows should be organized into logical stages. For example:

Start
  |
  v
Preparation
  |
  v
Processing
  |
  v
Validation
  |
  v
Completion

Each stage should contain related responsibilities. Avoid creating a single unnecessarily complex execution graph when smaller logical units make the application easier to understand.

Workflow Composition

Complex applications can contain multiple logical workflow processes. For example:

Application
    |
    +--> Research Workflow
    |
    +--> Processing Workflow
    |
    +--> Notification Workflow

Whether a particular BindAI release exposes a dedicated subworkflow API should be determined from the implemented workflow interface. Documentation should not assume a subworkflow API unless it has been verified.

Testing Workflow Definitions

Workflow construction should be tested through actual runtime behavior. Important V1 cases include:

Sequential execution
Agent execution
Tool execution
Condition true and false paths
Loop termination
Parallel branch execution
Join synchronization
Human-task approval
Human-task rejection
Workflow persistence
Connection-backed tool execution
Tool failures
Invalid workflow configuration

Testing should verify both workflow structure and executable behavior.

Design Principles

When constructing workflows:

Keep individual nodes focused.
Separate reasoning from deterministic operations.
Make control flow explicit.
Use conditions for routing.
Give loops clear termination conditions.
Use parallelism only for independent work.
Use Join nodes to synchronize parallel branches.
Use human tasks for explicit human decisions.
Keep external operations behind tools or connection-backed tools.
Preserve useful intermediate state.
Test failure paths as well as successful paths.
Avoid undocumented APIs.
Keep workflow construction separate from workflow execution.

Current BindAI V1 Scope

The current BindAI workflow construction and runtime foundation supports:

Workflow orchestration
Start and End nodes
Agent nodes
Tool nodes
Condition nodes
Loop nodes
Parallel nodes
Join nodes
Human Task nodes
Workflow variables and state
Persistent workflow execution state in Studio
Agent Memory
Agent Knowledge
Connection-backed tools
Webhook connections
Visual workflow editing
Studio API execution
Human-task pause and resume

The current V1 workflow system focuses on executable capabilities rather than configuration-only features.

Deferred Workflow Capabilities

The following capabilities are outside the current V1 scope:

Advanced retry policies
Advanced timeout policies
Workflow scheduling
Automation triggers
Distributed workflow execution
Advanced workflow monitoring
Additional external connection providers
Advanced Memory administration
Advanced Knowledge administration
MCP management

These capabilities can be added in later versions when they are implemented as complete working features.

Documentation Principle

Workflow documentation should distinguish between three layers:

Concept

The architectural idea behind a workflow feature.

Capability

A feature that BindAI currently implements.

Public API

The exact class, method, parameter, or configuration that users can call. For example:

Workflow Concept
       |
       v
Implemented Capability
       |
       v
Verified Public API

Only the final layer should be presented as executable API documentation. This keeps the documentation aligned with the actual BindAI implementation.

Summary

Workflow construction provides the structure required to coordinate complex BindAI applications. A workflow can combine:

Agents
   +
Tools
   +
Knowledge
   +
Memory
   +
Conditions
   +
Loops
   +
Parallel Execution
   +
Human Tasks
   +
Connections

The term Workflow Builder describes the workflow construction layer and should not be interpreted as a promise of a specific WorkflowBuilder class unless that API is implemented. BindAI Studio provides visual workflow construction, while the BindAI runtime executes the resulting workflow definitions. The important goal is to keep workflow definitions readable, testable, executable, and aligned with the actual BindAI implementation.

​Workflow Builder

​Why Use Structured Workflow Construction?

​Workflow Construction Lifecycle

​Workflow Definition

​Workflow Nodes

​Agents as Workflow Steps

​Tools as Workflow Steps

​Sequential Construction

​Conditional Construction

​Loop Construction

​Parallel Construction

​Join Construction

​Human Task Construction

​Workflow State

​Memory in Workflows

​Knowledge in Workflows

​Connections in Workflows

​Visual Workflow Construction

​Workflow Construction and Execution

​Workflow Execution Through the Studio API

​Workflow Persistence

​Builder APIs and Documentation Accuracy

​Builder vs Workflow Definition

​Validation

​Workflow Execution Errors

​Building Large Workflows

​Workflow Composition

​Testing Workflow Definitions

​Design Principles

​Current BindAI V1 Scope

​Deferred Workflow Capabilities

​Documentation Principle

​Concept

​Capability

​Public API

​Summary